package cgl.narada.event;

/** This class encapsulates various source and broker defined properties.
    EventProperties facilitates

    (a) The creation of both mutable and immutable properties. Immutable
    properties are never allowed to be changed after they are once set. 
    Mutable properties can be set several times.
    (b) Allows for the inspection of the original source properties
    (c) Allows for the inspection of intermediary properties. These properties
    could be set by the brokers or by other services.

    Note that:
    1. Immutable properties can not be modified after they have once been set
    2. You can track property changes only on immutable properties.
    3. You can not only track changes, but also the entities that initiated
    the changes on these properties.
    
    Note that:
    1. Immutable properties can not be modified after they have once been set
    2. You can track property changes only on immutable properties.
    3. You can not only track changes, but also the entities that initiated
    the changes on these properties.

    @author Shrideep Pallickara
    $Date$
    $Revision$
*/

import java.util.Enumeration;


public interface EventProperties {
  
  /** Check if there are any properties associated with the event */
  public boolean hasProperties();
  

  
  /** Retrieve the list of property names */
  public Enumeration getPropertyNames();
  

  /** Retrieve the list of property names with change tracking enabled. Note
      that this just returns the list of mutable properties that have change
      tracking enabled for them. */
  public Enumeration getPropertyNamesWithChangeTracking();
  
  
  /** Retrieve the value associated with a property. This method throws an
      exception if 
      <br>(a) This propertyName is not a valid one.
      <br>(b) The specified propertyName is NULL */
  public Object getProperty(Object propertyName) 
    throws NBEventException;
  
  
  
  /** Set a mutable property. This method throws an exception if 
      <br>(a) This property has been previously defined as a mutable property.
      <br>(b) Also neither the property or the property name can be NULL. */
  public void setMutableProperty(Object propertyName, Object property,
				 Object modifier) 
    throws NBEventException;
  
  
    
  /** Set an immutable property. This method throws an exception if 
      <br>(a) This immutable property already exists.  
      <br>(b) Also neither the property or the property name can be NULL. */
  public void setImmutableProperty(Object propertyName, Object property, 
				   Object creator)
    throws NBEventException;
  
  

  /** Check to see if this is a mutable property. This method throws an
      exception if 
      <br>(a) This property does not exist
      <br>(a) The specified propetyName is NULL  */
  public boolean isMutable(Object propertyName) throws NBEventException;

  
  /** Get the last modifier of a certain property. This method works with both
      mutable and immutable properties. This method throws an
      exception if 
      <br>(a) This property does not exist
      <br>(a) The specified propetyName is NULL  */
  public Object getLastModifier(Object propertyName) throws NBEventException;


  /** Track the changes to a specific property. This method throws an 
      exception if 
      <br>(a) This is an immutable property 
      <br>(b) If this property does not exist. 
      <br>(c) The specified propertyName is NULL  */
  public void trackPropertyChanges(Object propertyName)
    throws NBEventException;
  
  

  /** Indicates if property change tracking has been enabled for the 
      property in question. This method throws an exception if
      <br>(a) This property does not exist 
      <br>(b) The specified propertyName is not NULL */
  public boolean hasPropertyChangeTracking(Object propertyName)
    throws NBEventException;
  


  /** Get a list of the changes associated with a mutable property. This 
      method throws an exception if 
      <br>(a) changeTracking was not enabled on this property 
      <br>(b) The specified property does not exist
      <br>(c) The specified propertyName is NULL  */
  public Enumeration getPropertyChanges(Object propertyName)
    throws NBEventException;
  
  
  /** Gets alist of modifiers on a property. This method throws an exception 
      if 
      <br>(a) changeTracking was not enabled on this property 
      <br>(b) The specified property does not exist
      <br>(c) The specified propertyName is NULL  */
  public Enumeration getPropertyModifiers(Object propertyName) 
    throws NBEventException;
  
  
  /** Get a byte stream representation of the event header*/
  public byte[] getBytes();
  
  
  /** Indicates if the EventProperties has been modified since the last time
   * that it was serialized. */
  public boolean isModified();
  
}
